Szybki start sgcSign

W skrócie

Podpisujący i dostawca kluczy

Podpisujący zna format dokumentu. Dostawca kluczy wie, gdzie znajduje się klucz prywatny. Spotykają się na jednej właściwości.

Podpisujący

TsgcPAdESSigner, zadeklarowany w sgcSign_PAdES.pas i zarejestrowany na stronie palety SGC Sign. SignPDFFile przyjmuje ścieżkę wejściową i ścieżkę wyjściową.

Dostawca kluczy

TsgcWindowsCertStoreProvider dla magazynu certyfikatów Windows lub TsgcPFXKeyProvider dla pliku .pfx. Oba są na tej samej stronie palety.

Właściwość, która je łączy

KeyProvider, której typem jest interfejs IsgcKeyProvider, a nie odwołanie do komponentu. To rozróżnienie ma znaczenie dla czasu życia obiektów, a sekcja o problemach poniżej wyjaśnia dlaczego.

Platforma

Win32, Win64, Linux64, macOS na Intelu i Apple Silicon, iOS i Android. W systemie Windows haszowanie i podpisywanie przechodzą przez API Windows CNG, a na każdej innej platformie przez własną czystą kryptografię w Pascalu biblioteki, bez OpenSSL do wdrożenia. Dostawca magazynu certyfikatów Windows to jedyny komponent, który pozostaje tylko dla Windows.

Zanim zaczniesz

Wymagania i edycje

sgcSign nie ma poziomów funkcji, więc ta tabela dotyczy kompilatorów i platform, a nie edycji.

Co	Wartość
IDE	Od Delphi 7 do RAD Studio 13 oraz C++Builder. W przypadku C++Builder folder lib trafia na ścieżkę System Include, a nie na ścieżkę biblioteki.
Klauzula uses	Demo zawiera `sgcSign_Types, sgcSign_Interfaces, sgcSign_Classes, sgcSign_PAdES, sgcSign_KeyProvider_WinCertStore, sgcSign_KeyProvider_PEM, sgcSign_KeyProvider_PFX`. Pomiń dostawców, których nie używasz.
Edycje	Nie ma żadnych. Własny `sgcVer.inc` produktu w ogóle nie zawiera definu `SGC_EDT_*` i żadna funkcja nie jest ograniczona poziomem. Jedna biblioteka, każdy komponent, w każdej licencji. Poziomy komercyjne różnią się liczbą stanowisk: single, team i site, a do tego bezpłatna edycja Community.
Platforma, sprawdzona w źródłach	Win32, Win64, Linux64, OSX64, OSXARM64, iOS i Android. Kryptografia przechodzi przez jedną jednostkę-szew, `sgcSign_Crypto.pas`, czyli CNG w systemie Windows i czysty Pascal wszędzie indziej, HTTP to WinHTTP w systemie Windows i klient RTL Delphi gdzie indziej, a pakiety uruchomieniowe włączają Linux64 i macOS na Intelu od Delphi 10.3, Android i iOS od 10.4 oraz macOS na Apple Silicon od 11. `sgcSign_KeyProvider_WinCertStore.pas` to jedyna jednostka tylko dla Windows.
Zewnętrzne zależności	Brak. W systemie Windows biblioteka wywołuje bezpośrednio API Windows CNG i WinHTTP, a na pozostałych platformach używa własnej czystej kryptografii w Pascalu i klienta HTTP RTL Delphi, więc nie ma bibliotek DLL OpenSSL do wdrożenia z twoją aplikacją.
Wartości domyślne	Nowy `TsgcPAdESSigner` ma już użyteczny profil: konstruktor ustawia podstawowy profil PAdES, poziom podpisu baseline B i SHA-256. Nie musisz dotykać `Profile`, aby utworzyć prawidłowy podpis.

Wolisz XML od PDF? Pięciominutowy opis XAdES podpisuje dokument XML za pomocą pliku PFX i omawia pułapkę Unicode w Delphi 7 oraz czas podpisu w UTC. Ta strona to odpowiednik dla PDF i magazynu certyfikatów.

Krok 1

Zainstaluj i znajdź stronę palety

Skompiluj pakiet uruchomieniowy przed zainstalowaniem pakietu czasu projektowania, ponieważ ten drugi odwołuje się do pierwszego.

1. Rozpakuj

Rozpakuj pobrany plik do folderu, który poniżej nazywamy {$DIR}.

2. Ścieżka biblioteki

Tools, Environment Options, Directories. Dodaj {$DIR}\delphi\source, co dotyczy każdej wersji RAD Studio.

3. Dodaj folder lib

Dodaj także folder zależny od wersji, na przykład {$DIR}\delphi\libD13\$(Platform) w RAD Studio 13, aż do libD7 w Delphi 7. Dla C++Builder trafiają one zamiast tego na ścieżkę System Include.

4. Zbuduj pakiety

Otwórz Packages\sgcSignD13.groupproj dla swojej wersji IDE lub sgcSignC13.groupproj dla C++Builder. Najpierw skompiluj pakiet sgcSign, a potem zainstaluj dclsgcSign.

5. Sprawdź paletę

Pojawia się strona o nazwie SGC Sign, zawierająca podpisujących, weryfikatora, klientów znaczników czasu i OCSP oraz dziesięciu dostawców kluczy. W systemie Windows zawiera także podpisującego i weryfikatora Authenticode.

QuickStart

Podpisz PDF w około dwudziestu linijkach

Wybierz certyfikat, utwórz podpisującego, wskaż mu dostawcę i wywołaj SignPDFFile. Pierwsza karta używa magazynu certyfikatów Windows, druga pliku PFX.

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;

Zwróć uwagę, czego tu nie ma. Profile nigdy nie jest ruszany, ponieważ konstruktor już ustawia podstawowy profil PAdES, poziom podpisu baseline B i SHA-256. Komentarz o tymczasowym interfejsie pochodzi z dostarczanego dema, a kolejność zwalniania w bloku finally jest powodem, dla którego ma znaczenie.

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;

Jedyna różnica względem pierwszej karty to dostawca, którego tworzysz, i sposób wskazania mu klucza. Wszystko od KeyProvider := wzwyż jest identyczne i dotyczy to wszystkich dziesięciu dostawców, w tym sprzętu PKCS#11 i usług kluczy w chmurze.

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;

Ta sama zasada interfejsu co dla podpisującego: przypisz rzutowanie do nazwanej zmiennej lokalnej i wyczyść je przed zwolnieniem komponentu. GetValidationReportXML tworzy raport w formacie raportu walidacji ETSI, gdy wartość logiczna to za mało dowodów.

Pierwsze dwie karty pochodzą z dostarczanego dema Demos\Delphi\PAdES\frmMain.pas, z rozgałęzieniami zredukowanymi do jednej ścieżki na kartę. Komentarz o trzymaniu interfejsu w nazwanej zmiennej lokalnej pochodzi z dema i warto go zachować. Bogatsze demo siostrzane, Demos\Delphi\PAdES_Providers, robi to samo ze sprzętowymi i chmurowymi dostawcami.

Krok 2

Sprawdź podpis, nie patrz tylko na plik

Plik się pojawił. To nie to samo, co podpis, który przechodzi walidację.

Certyfikat został rozpoznany

Odczytaj Certificate.Subject po wyborze, tak jak robi to demo. To różnica między podpisaniem certyfikatem, który miałeś na myśli, a podpisaniem tym, który pasował jako pierwszy. IsLoaded odpowiada na to samo pytanie jako wartość logiczna.

Plik się pojawił

SignPDFFile zapisuje ścieżkę wyjściową, którą mu podałeś. Dostarczane demo wyprowadza ją przez ChangeFileExt, aby podpisany plik trafił obok oryginału.

Zgłasza wyjątek, nie zwraca kodu

Nie ma wyniku do sprawdzenia, więc umieść wywołanie w try except i odczytaj komunikat wyjątku. Tak robi demo i to jedyny kanał błędów.

Podpis przechodzi walidację

Plik to nie jest prawidłowy podpis. TsgcSignatureVerifier.VerifyPDF zwraca TsgcVerificationStatus, który porównujesz z vsValid, a GetVerificationDetails wyjaśnia niepowodzenie. Otwarcie pliku w czytniku PDF pokazuje człowiekowi to samo.

Typowe problemy

Co zwykle idzie nie tak za pierwszym razem

Sześć problemów odpowiada za niemal każdy pierwszy podpis.

Naruszenie dostępu przy wyjściu

To ten, przed którym demo ostrzega we własnym komentarzu. KeyProvider przyjmuje IsgcKeyProvider, więc wbudowane rzutowanie as zostawia wygenerowane przez kompilator odwołanie do interfejsu przy życiu aż do powrotu z procedury, czyli po zwolnieniu komponentu dostawcy. Przypisz interfejs do nazwanej zmiennej lokalnej i zwalniaj w kolejności: podpisujący, potem interfejs ustawiony na nil, potem dostawca.

Profile nie jest tekstem

To obiekt TsgcSignProfileConfig. Ustawiasz Profile.Profile i Profile.SignatureLevel, a nie Profile := 'something'. Konstruktor już wypełnia użyteczną wartość domyślną, więc pierwszy przykład w ogóle nie musi jej ruszać.

Nie znaleziono certyfikatu

SelectCertificateBySubject dopasowuje po temacie, a SelectCertificateByThumbprint po odcisku. Odczytaj Certificate.Subject po wyborze, tak jak robi to demo, aby zobaczyć, jaki certyfikat faktycznie dostałeś. EnumerateCertificates wylicza dostępne.

Nie kompiluje się poza Windows

Nie może. Podpisujący i każdy dostawca umieszczają Windows w klauzuli uses interfejsu bez warunku, więc jest to błąd kompilacji, a nie pusta jednostka. sgcSign to biblioteka dla Windows.

Podpis jest w czytniku pokazywany jako nieznany

Podstawowy podpis nie niesie kotwicy zaufania ani danych o unieważnieniu. Dodaj znacznik czasu przez TSAClient i przejdź na profil długoterminowy, gdy dokument musi pozostać weryfikowalny po wygaśnięciu certyfikatu.

SignPDFFile zgłasza wyjątek zamiast zwracać kod

Tak jest zaprojektowane. Nie ma wartości zwracanej do sprawdzenia, więc umieść wywołanie w try except i odczytaj komunikat wyjątku, co robi dostarczane demo.

Zgłęb temat

Poza pierwszym podpisem

Cztery kierunki, wszystkie w tej samej bibliotece.

Inne formaty dokumentów

XAdES i XMLDSig dla XML, CAdES dla oddzielonego CMS, kontenery ASiC oraz dedykowani podpisujący dla pakietów ClickOnce, NuGet i VSIX. W systemie Windows jest także podpisujący Authenticode.

Wszystkie komponenty sgcSign

Gdzie znajduje się klucz

W pakiecie jest dziesięciu dostawców kluczy: PFX, PEM, magazyn Windows, sprzęt PKCS#11, Azure Trusted Signing, AWS KMS, Google Cloud KMS, Certum SimplySign, HashiCorp Vault i protokół zdalnego podpisywania CSC.

Dostawcy kluczy

Profile krajowe

Dwadzieścia jeden profili krajowych i branżowych, od hiszpańskiego VeriFactu po unijne formaty faktur, każdy z polami i poziomem podpisu, jakich oczekuje dany reżim.

Profile podpisu

Podpisuj gdzie indziej

sgcSign Server to samodzielnie hostowany demon, który przechowuje klucze i podpisuje na żądanie, więc certyfikat nigdy nie opuszcza maszyny, której ufasz.

sgcSign Server

Zasoby

Dokumentacja, dema i materiały

Projekty demo znajdują się w pobranym pakiecie, w Demos\Delphi. Demo PAdES to to, na którym zbudowana jest ta strona.

	Pięciominutowy opis XAdES Rozbudowany szybki start: nowy projekt VCL, plik PFX i podpisana koperta XML.	Otwórz
	Dostawcy kluczy Wszystkie dziesięć miejsc, w których może znajdować się klucz prywatny, i czego każde wymaga.	Otwórz
	Profile podpisu Dwadzieścia jeden profili krajowych i branżowych oraz to, czego każdy wymaga.	Otwórz
	Samouczek podpisywania PDF Dłuższy opis PAdES, w tym widoczne podpisy.	Otwórz
	sgcSign Server Samodzielnie hostowany demon podpisujący, gdy klucz nie może podróżować.	Otwórz
	Pobierz wersję próbną Ten sam instalator co w wersji produkcyjnej, z ograniczeniem czasowym, a także bezpłatna edycja Community.	Otwórz

Powiązane lektury: wprowadzenie do sgcSign oraz serwer podpisywania kodu. Każdy produkt ma własny szybki start, wymieniony na stronie pierwszych kroków.

FAQ

Pytania o szybki start sgcSign

TsgcPAdESSigner, zadeklarowany w sgcSign_PAdES.pas, oraz dostawca kluczy. Dla magazynu certyfikatów Windows jest to TsgcWindowsCertStoreProvider, z sgcSign_KeyProvider_WinCertStore.pas. Dla pliku .pfx jest to TsgcPFXKeyProvider, z sgcSign_KeyProvider_PFX.pas. Oba znajdują się na stronie palety SGC Sign. Przypisz dostawcę do właściwości KeyProvider podpisującego, a następnie wywołaj SignPDFFile(aInputFile, aOutputFile).

Ponieważ KeyProvider jest typowany jako interfejs IsgcKeyProvider, a nie jako komponent. Wbudowane rzutowanie as tworzy wygenerowany przez kompilator tymczasowy interfejs, który pozostaje przy życiu w ramce stosu aż do powrotu z procedury, czyli po zwolnieniu komponentu dostawcy, a jego zwolnienie wtedy dotyka pamięci, której już nie ma. Demo przypisuje rzutowanie do nazwanej zmiennej lokalnej, a potem zwalnia w kolejności: podpisujący, interfejs ustawiony na nil, dostawca. Skopiuj tę kolejność.

Nie ma edycji. sgcVer.inc produktu w ogóle nie zawiera definu SGC_EDT_* i żaden komponent ani format nie jest ograniczony poziomem. Każda licencja zawiera każdego podpisującego, każdego dostawcę kluczy i każdy profil krajowy. Poziomy komercyjne to liczby stanowisk, single, team i site, a obok wersji próbnej jest bezpłatna edycja Community.

Tak, od wersji 2026.10.0. Biblioteka buduje się i działa w Linux64, w macOS na Intelu i Apple Silicon, w iOS i na Androidzie, a także w Win32 i Win64. Podpisywanie i weryfikowanie dokumentów, odczyt i zapis plików PKCS#12, podpisywanie plików PE, katalogów, MSI, MSP, MSIX i APPX oraz tokeny PKCS#11 działają tam wszystkie, a serwer podpisujący działa jako demon systemd w Linuksie. Dwóch dostawców używa magazynu kluczy, który platforma już ma, czyli pęku kluczy Apple i Android KeyStore. Dwie rzeczy pozostają w systemie Windows: dostawca magazynu certyfikatów Windows oraz formaty specyficzne dla Windows w serwerze i narzędziu wiersza poleceń, które nadal odmawiają ich obsługi w kompilacji innej niż Windows, mimo że sama biblioteka je podpisuje.

Nie przy pierwszym podpisie. Konstruktor już ustawia podstawowy profil PAdES, poziom podpisu baseline B i SHA-256. Gdy chcesz to zmienić, Profile jest obiektem TsgcSignProfileConfig, więc ustawiasz Profile.Profile i Profile.SignatureLevel, a nie przypisujesz tekst. Dla podpisu długoterminowego przejdź na profil LTV i poziom baseline LT oraz dołącz TSAClient.

Użyj TsgcSignatureVerifier. VerifyPDF przyjmuje strumień i zwraca TsgcVerificationStatus, który porównujesz z vsValid. GetVerificationDetails wyjaśnia niepowodzenie, a GetValidationReportXML tworzy raport w formacie raportu walidacji ETSI, gdy potrzebujesz dowodu, a nie wartości logicznej.

Nie. W systemie Windows sgcSign haszuje i podpisuje przez API CNG i BCrypt, a z siecią komunikuje się przez WinHTTP. W Linuksie, macOS, iOS i na Androidzie używa własnej czystej kryptografii w Pascalu i klienta HTTP RTL Delphi. W obu przypadkach nie ma bibliotek DLL OpenSSL do dostarczenia, co jest jednym z powodów, dla których wdrożenie jest proste.

Celowo obejmują różne zadania. Pięciominutowy szybki start buduje nowy projekt VCL, używa pliku PFX i podpisuje dokument XML za pomocą XAdES, a także omawia pułapkę Unicode w Delphi 7 i czas podpisu w UTC. Ta strona podpisuje PDF za pomocą PAdES, używając certyfikatu z magazynu Windows, co robi dostarczane demo PAdES. Przeczytaj najpierw tę, a potem tamtą, gdy będziesz potrzebować XML.

sgcSign w pięć minut