sgcSign Hızlı Başlangıç

Bir bakışta

Bir imzalayıcı ve bir anahtar sağlayıcı

İmzalayıcı belge biçimini bilir. Anahtar sağlayıcı özel anahtarın nerede durduğunu bilir. İkisi tek bir özellikte buluşur.

İmzalayıcı

sgcSign_PAdES.pas içinde bildirilen ve SGC Sign palet sayfasına kaydedilen TsgcPAdESSigner. SignPDFFile bir girdi yolu ve bir çıktı yolu alır.

Anahtar sağlayıcı

Windows sertifika deposu için TsgcWindowsCertStoreProvider veya bir .pfx dosyası için TsgcPFXKeyProvider. İkisi de aynı palet sayfasındadır.

İkisini birleştiren özellik

Türü bir bileşen başvurusu değil IsgcKeyProvider arayüzü olan KeyProvider. Bu ayrım ömür açısından önemlidir ve aşağıdaki tuzaklar bölümü nedenini açıklar.

Platform

Win32, Win64, Linux64, Intel ve Apple Silicon üzerinde macOS, iOS ve Android. Windows'ta karma ve imzalama Windows CNG API'si üzerinden, diğer tüm platformlarda kitaplığın kendi saf Pascal kriptografisi üzerinden yapılır; dağıtılacak OpenSSL yoktur. Windows sertifika deposu sağlayıcısı yalnızca Windows'ta kalan tek bileşendir.

Başlamadan önce

Gereksinimler ve sürümler

sgcSign'ın özellik kademeleri yoktur; bu nedenle bu tablo sürümlerle değil derleyicilerle ve platformlarla ilgilidir.

Konu	Değer
IDE	Delphi 7'den RAD Studio 13'e ve C++Builder. C++Builder yolunda lib klasörü kitaplık yoluna değil System Include yoluna konur.
Uses yan tümcesi	Demo şunu yazar: `sgcSign_Types, sgcSign_Interfaces, sgcSign_Classes, sgcSign_PAdES, sgcSign_KeyProvider_WinCertStore, sgcSign_KeyProvider_PEM, sgcSign_KeyProvider_PFX`. Kullanmadığınız sağlayıcıları çıkarın.
Sürümler	Hiç yok. Ürünün kendi `sgcVer.inc` dosyasında hiçbir `SGC_EDT_*` tanımı yoktur ve hiçbir özellik kademeyle kısıtlanmaz. Bir kitaplık, her bileşen, her lisansta. Ticari kademeler kullanıcı sayısınadır: single, team ve site; ayrıca ücretsiz bir Community Edition.
Platform, kaynakta doğrulanmış	Win32, Win64, Linux64, OSX64, OSXARM64, iOS ve Android. Kriptografi tek bir bağlantı unit'i olan `sgcSign_Crypto.pas` üzerinden geçer; bu unit Windows'ta CNG, diğer her yerde saf Pascal'dır. HTTP, Windows'ta WinHTTP, başka yerlerde Delphi RTL istemcisidir. Çalışma zamanı paketleri Linux64 ve Intel üzerinde macOS'u Delphi 10.3'ten, Android ve iOS'u 10.4'ten, Apple Silicon üzerinde macOS'u ise 11'den itibaren etkinleştirir. `sgcSign_KeyProvider_WinCertStore.pas` yalnızca Windows'a özgü tek unit'tir.
Dış bağımlılıklar	Yok. Windows'ta kitaplık Windows CNG ve WinHTTP API'lerini doğrudan çağırır, diğer platformlarda kendi saf Pascal kriptografisini ve Delphi RTL HTTP istemcisini kullanır; bu nedenle uygulamanızla birlikte dağıtılacak OpenSSL DLL'i yoktur.
Varsayılanlar	Yeni bir `TsgcPAdESSigner` zaten kullanılabilir bir profile sahiptir: oluşturucu temel PAdES profilini, temel B imza düzeyini ve SHA-256'yı ayarlar. Geçerli bir imza üretmek için `Profile` değerine dokunmanız gerekmez.

PDF yerine XML mi tercih ediyorsunuz? Beş dakikalık XAdES anlatımı bunun yerine bir PFX dosyasıyla bir XML belgesini imzalar, ayrıca Delphi 7 Unicode tuzağını ve UTC imza zamanını kapsar. Bu sayfa, PDF ve sertifika deposu karşılığıdır.

1. Adım

Kurun ve palet sayfasını bulun

Tasarım zamanı paketini kurmadan önce çalışma zamanı paketini derleyin, çünkü ikincisi birincisine başvurur.

1. Zip dosyasını açın

İndirdiğiniz dosyayı aşağıda {$DIR} olarak adlandırılan bir klasöre açın.

2. Kitaplık yolu

Tools, Environment Options, Directories. Her RAD Studio sürümü için geçerli olan {$DIR}\delphi\source yolunu ekleyin.

3. Lib klasörünü ekleyin

Sürüme özgü klasörü de ekleyin; örneğin RAD Studio 13'te {$DIR}\delphi\libD13\$(Platform), Delphi 7'de libD7'ye kadar. C++Builder için bunlar bunun yerine System Include yoluna konur.

4. Paketleri derleyin

IDE sürümünüz için Packages\sgcSignD13.groupproj dosyasını veya C++Builder için sgcSignC13.groupproj dosyasını açın. Önce sgcSign paketini derleyin, ardından dclsgcSign paketini kurun.

5. Paleti kontrol edin

İmzalayıcıları, doğrulayıcıyı, zaman damgası ve OCSP istemcilerini ve on anahtar sağlayıcıyı içeren SGC Sign adlı bir sayfa görünür. Windows'ta ayrıca Authenticode imzalayıcısını ve doğrulayıcısını da taşır.

QuickStart

Bir PDF'i yaklaşık yirmi satırda imzalayın

Bir sertifika seçin, imzalayıcıyı oluşturun, sağlayıcıya yöneltin ve SignPDFFile çağırın. İlk sekme Windows sertifika deposunu, ikincisi bir PFX dosyasını kullanır.

frmMain.pas

uses
  SysUtils, Classes,
  // sgcSign
  sgcSign_Types, sgcSign_Interfaces, sgcSign_Classes,
  sgcSign_PAdES, sgcSign_KeyProvider_WinCertStore;

procedure TFormMain.btnSignClick(Sender: TObject);
var
  vSigner: TsgcPAdESSigner;
  vKeyProvider: TsgcWindowsCertStoreProvider;
  vProviderIntf: IsgcKeyProvider;
  vOutputFile: string;
begin
  vKeyProvider := TsgcWindowsCertStoreProvider.Create(nil);
  vSigner := TsgcPAdESSigner.Create(nil);
  try
    vKeyProvider.SelectCertificateBySubject('My Company');
    Log('Certificate found: ' + vKeyProvider.Certificate.Subject);

    // Hold the interface in an explicit local: an inline "as" cast
    // would leave a compiler-generated interface temporary alive in
    // this stack frame until the routine returns, i.e. past
    // vKeyProvider.Free, and releasing it would touch freed memory.
    vProviderIntf := vKeyProvider as IsgcKeyProvider;
    vSigner.KeyProvider := vProviderIntf;
    vSigner.Reason := 'Demo signature';
    vSigner.Location := 'Spain';
    vSigner.SignerName := 'sgcSign Demo';

    vOutputFile := ChangeFileExt(edInputFile.Text, '_signed.pdf');
    vSigner.SignPDFFile(edInputFile.Text, vOutputFile);

    Log('SUCCESS: PDF signed with PAdES profile');
    Log('Output file: ' + vOutputFile);
  finally
    vSigner.Free;
    vProviderIntf := nil;
    vKeyProvider.Free;
  end;
end;

Burada ne olmadığına dikkat edin. Profile değerine hiç dokunulmaz, çünkü oluşturucu zaten temel bir PAdES profilini, temel B imza düzeyini ve SHA-256'yı ayarlar. Arayüz geçici nesnesiyle ilgili yorum pakette gelen demonun kendisine aittir ve finally bloğundaki serbest bırakma sırası bunun neden önemli olduğunun nedenidir.

frmMain.pas

uses
  SysUtils, Classes,
  // sgcSign
  sgcSign_Types, sgcSign_Interfaces, sgcSign_Classes,
  sgcSign_PAdES, sgcSign_KeyProvider_PFX;

var
  vSigner: TsgcPAdESSigner;
  vKeyProvider: TsgcPFXKeyProvider;
  vProviderIntf: IsgcKeyProvider;
begin
  vKeyProvider := TsgcPFXKeyProvider.Create(nil);
  vSigner := TsgcPAdESSigner.Create(nil);
  try
    vKeyProvider.FileName := 'C:\certs\signer.pfx';
    vKeyProvider.Password := GetPfxPassword;
    vKeyProvider.LoadFromFile;
    Log('Certificate loaded (PFX): ' + vKeyProvider.Certificate.Subject);

    vProviderIntf := vKeyProvider as IsgcKeyProvider;
    vSigner.KeyProvider := vProviderIntf;

    vSigner.SignPDFFile('C:\docs\contract.pdf',
      'C:\docs\contract_signed.pdf');
  finally
    vSigner.Free;
    vProviderIntf := nil;
    vKeyProvider.Free;
  end;
end;

İlk sekmeden tek fark, hangi sağlayıcıyı oluşturduğunuz ve onu bir anahtara nasıl yönelttiğinizdir. KeyProvider := ifadesinden sonrası aynıdır ve bu, PKCS#11 donanımı ve bulut anahtar hizmetleri dahil on sağlayıcının hepsi için geçerlidir.

uVerify.pas

uses
  SysUtils, Classes,
  // sgcSign
  sgcSign_Types, sgcSign_Interfaces, sgcSign_Verifier;

var
  oVerifier: TsgcSignatureVerifier;
  vVerifier: IsgcSignatureVerifier;
  oStream: TFileStream;
begin
  oVerifier := TsgcSignatureVerifier.Create(nil);
  oStream := TFileStream.Create('C:\docs\contract_signed.pdf',
    fmOpenRead or fmShareDenyWrite);
  try
    // VerifyPDF is reached through the interface the component implements
    vVerifier := oVerifier as IsgcSignatureVerifier;

    if vVerifier.VerifyPDF(oStream) = vsValid then
      Writeln('valid')
    else
      Writeln(oVerifier.GetVerificationDetails);
  finally
    vVerifier := nil;
    oStream.Free;
    oVerifier.Free;
  end;
end;

İmzalayıcıyla aynı arayüz kuralı: dönüştürmeyi adlandırılmış bir yerel değişkene atayın ve bileşeni serbest bırakmadan önce temizleyin. GetValidationReportXML, bir boolean yeterli kanıt olmadığında ETSI doğrulama raporu biçiminde bir rapor üretir.

İlk iki sekme, dallanması sekme başına tek bir yola indirilmiş olarak paketle gelen Demos\Delphi\PAdES\frmMain.pas demosundan alınmıştır. Arayüzü adlandırılmış bir yerelde tutmayla ilgili yorum demonun kendisine aittir ve korunmaya değer. Daha zengin kardeş demo Demos\Delphi\PAdES_Providers, aynı işi donanım ve bulut sağlayıcılarıyla yapar.

2. Adım

İmzayı kontrol edin, yalnızca dosyaya bakmayın

Bir dosya göründü. Bu, doğrulanan bir imzayla aynı şey değildir.

Sertifika çözüldü

Demonun yaptığı gibi seçtikten sonra Certificate.Subject değerini okuyun. Bu, kastettiğiniz sertifikayla imzalamakla ilk eşleşen sertifikayla imzalamak arasındaki farktır. IsLoaded aynı soruyu bir boolean olarak yanıtlar.

Dosya göründü

SignPDFFile, verdiğiniz çıktı yoluna yazar. Pakette gelen demo bunu ChangeFileExt ile türetir; böylece imzalı dosya orijinalin yanına düşer.

Kod döndürmez, istisna oluşturur

Sınanacak bir sonuç yoktur; bu nedenle çağrıyı bir try except içine koyun ve istisna iletisini okuyun. Demo bunu yapar ve tek başarısızlık kanalı budur.

İmza doğrulanıyor

Bir dosya geçerli bir imza değildir. TsgcSignatureVerifier.VerifyPDF, vsValid ile karşılaştırdığınız bir TsgcVerificationStatus döndürür ve GetVerificationDetails bir başarısızlığı açıklar. Dosyayı bir PDF okuyucuda açmak aynı şeyi bir kişiye gösterir.

Sık karşılaşılan sorunlar

İlk seferde genellikle ne ters gider

İlk imzaların neredeyse tamamı altı sorundan kaynaklanır.

Çıkışta bir erişim ihlali

Demonun kendi yorumunda uyardığı budur. KeyProvider bir IsgcKeyProvider alır; bu nedenle satır içi bir as dönüştürmesi, derleyicinin ürettiği bir arayüz başvurusunu rutin dönene kadar, yani sağlayıcı bileşenini serbest bıraktıktan sonrasına kadar canlı bırakır. Arayüzü adlandırılmış bir yerele atayın ve sırasıyla imzalayıcıyı, ardından arayüzü nil yaparak, sonra sağlayıcıyı serbest bırakın.

Profile bir dize değildir

Bir TsgcSignProfileConfig nesnesidir. Profile := 'something' değil, Profile.Profile ve Profile.SignatureLevel değerlerini ayarlarsınız. Oluşturucu zaten kullanılabilir bir varsayılan doldurur; bu nedenle ilk örneğin ona hiç dokunması gerekmez.

Hiç sertifika bulunamıyor

SelectCertificateBySubject konuya göre, SelectCertificateByThumbprint ise parmak izine göre eşleştirir. Gerçekte hangi sertifikayı aldığınızı görebilmek için demonun yaptığı gibi seçtikten sonra Certificate.Subject değerini okuyun. EnumerateCertificates mevcut olanları listeler.

Windows deposu sağlayıcısı Windows dışında derlenmiyor

TsgcWindowsCertStoreProvider, sgcSign_KeyProvider_WinCertStore.pas içindedir ve yalnızca Windows'ta derlenen tek unit'tir. Linux, macOS, iOS ve Android'de PFX, PEM, PKCS#11 veya bulut sağlayıcılarından biri gibi başka bir anahtar sağlayıcısı seçin; kitaplığın geri kalanı aynı şekilde çalışır.

İmza okuyucuda bilinmiyor olarak görünüyor

Temel bir imza güven çıpası ve iptal verisi taşımaz. TSAClient aracılığıyla bir zaman damgası ekleyin ve belge sertifika sona erdikten sonra da doğrulanabilir kalmak zorundaysa uzun vadeli bir profile geçin.

SignPDFFile kod döndürmek yerine istisna oluşturuyor

Tasarım böyledir. Sınanacak bir dönüş değeri yoktur; bu nedenle çağrıyı bir try except içine koyun ve istisna iletisini okuyun; pakette gelen demo bunu yapar.

Daha derine inin

İlk imzanın ötesinde

Dört yön, hepsi aynı kitaplığın içinde.

Diğer belge biçimleri

XML için XAdES ve XMLDSig, ayrık CMS için CAdES, ASiC kapsayıcıları ve ClickOnce, NuGet ve VSIX paketleri için özel imzalayıcılar. Windows'ta ayrıca bir Authenticode imzalayıcısı da vardır.

Tüm sgcSign bileşenleri

Anahtar nerede duruyor

On anahtar sağlayıcı gelir: PFX, PEM, Windows deposu, PKCS#11 donanımı, Azure Trusted Signing, AWS KMS, Google Cloud KMS, Certum SimplySign, HashiCorp Vault ve CSC uzaktan imzalama protokolü.

Anahtar sağlayıcılar

Ülke profilleri

İspanya VeriFactu'dan AB fatura biçimlerine kadar yirmi bir ülke ve sektör profili; her biri o rejimin beklediği alanlarla ve imza düzeyiyle birlikte.

İmza profilleri

Başka bir yerde imzalayın

sgcSign Server, anahtarları tutan ve istek üzerine imzalayan, kendi altyapınızda barındırılan bir daemon'dur; böylece sertifika, ona güvendiğiniz makineden hiç ayrılmaz.

sgcSign Server

Kaynaklar

Başvuru, demolar ve belgeler

Demo projeleri indirmenin içinde, Demos\Delphi altında gelir. Bu sayfanın dayandığı demo PAdES demosudur.

	Beş dakikalık XAdES anlatımı Uzun biçimli hızlı başlangıç: yeni bir VCL projesi, bir PFX dosyası ve imzalı bir XML zarfı.	Aç
	Anahtar sağlayıcılar Bir özel anahtarın durabileceği on yerin hepsi ve her birinin neye ihtiyaç duyduğu.	Aç
	İmza profilleri Yirmi bir ülke ve sektör profili ve her birinin gerektirdikleri.	Aç
	PDF imzalama eğitimi Görünür imzalar dahil PAdES'in daha uzun bir anlatımı.	Aç
	sgcSign Server Anahtarın yolculuk etmemesi gerektiğinde, kendi altyapınızda barındırılan imzalama daemon'u.	Aç
	Denemeyi indirin Üretimle aynı yükleyici, süre sınırlı; ayrıca ücretsiz bir Community Edition.	Aç

İlgili okumalar: sgcSign'a giriş ve kod imzalama sunucusu. Her ürünün kendi hızlı başlangıcı vardır ve başlarken sayfasında listelenir.

SSS

sgcSign hızlı başlangıç soruları

sgcSign_PAdES.pas içinde bildirilen TsgcPAdESSigner ve bir anahtar sağlayıcı. Windows sertifika deposu için bu, sgcSign_KeyProvider_WinCertStore.pas içinden TsgcWindowsCertStoreProvider bileşenidir. Bir .pfx dosyası için sgcSign_KeyProvider_PFX.pas içinden TsgcPFXKeyProvider bileşenidir. İkisi de SGC Sign palet sayfasında bulunur. Sağlayıcıyı imzalayıcının KeyProvider özelliğine atayın, ardından SignPDFFile(aInputFile, aOutputFile) çağırın.

Çünkü KeyProvider bir bileşen olarak değil, IsgcKeyProvider arayüzü olarak türlendirilmiştir. Satır içi bir as dönüştürmesi, rutin dönene kadar, yani sağlayıcı bileşeni serbest bırakıldıktan sonrasına kadar yığın çerçevesinde canlı kalan, derleyicinin ürettiği bir arayüz geçici nesnesi oluşturur ve onu o noktada serbest bırakmak artık var olmayan belleğe dokunur. Demo dönüştürmeyi adlandırılmış bir yerele atar ve ardından imzalayıcı, nil yapılan arayüz, sağlayıcı sırasıyla serbest bırakır. Bu sırayı kopyalayın.

Sürüm yoktur. Ürünün sgcVer.inc dosyasında hiçbir SGC_EDT_* tanımı yoktur ve hiçbir bileşen veya biçim kademeyle kısıtlanmaz. Her lisans her imzalayıcıyı, her anahtar sağlayıcıyı ve her ülke profilini içerir. Ticari kademeler kullanıcı sayısıdır: single, team ve site; ayrıca denemenin yanında ücretsiz bir Community Edition vardır.

Evet, 2026.10.0 sürümünden itibaren. Kitaplık Win32 ve Win64'ün yanı sıra Linux64'te, Intel ve Apple Silicon üzerinde macOS'ta, iOS'ta ve Android'de derlenir ve çalışır. Belgeleri imzalama ve doğrulama, PKCS#12 dosyalarını okuma ve yazma, PE dosyalarını, katalogları, MSI, MSP, MSIX ve APPX paketlerini imzalama ve PKCS#11 belirteçleri orada çalışır; imzalama sunucusu ise Linux'ta bir systemd daemon'u olarak çalışır. İki sağlayıcı platformun zaten sahip olduğu anahtar deposunu kullanır: Apple anahtar zinciri ve Android KeyStore. İki şey Windows'ta kalır: Windows sertifika deposu sağlayıcısı ve sunucudaki ile komut satırı aracındaki Windows'a özgü biçimler; kitaplığın kendisi bunları imzalasa da bunlar Windows olmayan bir derlemede hâlâ reddedilir.

İlk imza için gerekmez. Oluşturucu zaten temel bir PAdES profilini, temel B imza düzeyini ve SHA-256'yı ayarlar. Değiştirmek istediğinizde Profile bir TsgcSignProfileConfig nesnesidir; bu nedenle bir dize atamak yerine Profile.Profile ve Profile.SignatureLevel değerlerini ayarlarsınız. Uzun vadeli bir imza için LTV profiline ve temel LT düzeyine geçin ve bir TSAClient ekleyin.

TsgcSignatureVerifier kullanın. VerifyPDF bir akış alır ve vsValid ile karşılaştırdığınız bir TsgcVerificationStatus döndürür. GetVerificationDetails bir başarısızlığı açıklar ve GetValidationReportXML, bir boolean yerine kanıta ihtiyaç duyduğunuzda ETSI doğrulama raporu biçiminde bir rapor üretir.

Hayır. Windows'ta sgcSign karma ve imzalama işlemlerini CNG ve BCrypt API'leri üzerinden yapar ve ağla WinHTTP üzerinden konuşur. Linux, macOS, iOS ve Android'de kendi saf Pascal kriptografisini ve Delphi RTL HTTP istemcisini kullanır. Her iki durumda da gönderilecek OpenSSL DLL'i yoktur; dağıtımın basit olmasının nedenlerinden biri budur.

Bilerek farklı işleri kapsarlar. Beş dakikalık hızlı başlangıç yeni bir VCL projesi oluşturur, bir PFX dosyası kullanır ve bir XML belgesini XAdES ile imzalar; ayrıca Delphi 7 Unicode tuzağını ve UTC imza zamanını ele alır. Bu sayfa, Windows deposundaki bir sertifikayla bir PDF'i PAdES ile imzalar; pakette gelen PAdES demosunun yaptığı budur. Önce bunu, XML'e ihtiyaç duyduğunuzda da onu okuyun.

sgcSign beş dakikada