Guida rapida di sgcSign

In sintesi

Un firmatario e un key provider

Il firmatario conosce il formato del documento. Il key provider sa dove si trova la chiave privata. Si incontrano su una sola proprietà.

Il firmatario

TsgcPAdESSigner, dichiarato in sgcSign_PAdES.pas e registrato nella pagina SGC Sign della palette. SignPDFFile accetta un percorso di input e un percorso di output.

Il key provider

TsgcWindowsCertStoreProvider per lo store dei certificati di Windows, oppure TsgcPFXKeyProvider per un file .pfx. Entrambi sono nella stessa pagina della palette.

La proprietà che li unisce

KeyProvider, il cui tipo è l'interfaccia IsgcKeyProvider e non un riferimento a un componente. Questa distinzione conta per la durata di vita e la sezione sui problemi qui sotto ne spiega il motivo.

Piattaforma

Win32, Win64, Linux64, macOS su Intel e Apple Silicon, iOS e Android. Su Windows l'hashing e la firma passano dall'API CNG di Windows, su ogni altra piattaforma dalla crittografia Pascal pura della libreria, senza OpenSSL da distribuire. Il provider dello store dei certificati di Windows è l'unico componente che resta solo per Windows.

Prima di iniziare

Requisiti ed edizioni

sgcSign non ha livelli di funzionalità, quindi questa tabella riguarda compilatori e piattaforme e non le edizioni.

Cosa	Valore
IDE	Da Delphi 7 a RAD Studio 13 e C++Builder. Per C++Builder la cartella lib va nel System Include path invece che nel library path.
Clausola uses	La demo scrive `sgcSign_Types, sgcSign_Interfaces, sgcSign_Classes, sgcSign_PAdES, sgcSign_KeyProvider_WinCertStore, sgcSign_KeyProvider_PEM, sgcSign_KeyProvider_PFX`. Elimina i provider che non usi.
Edizioni	Non ce ne sono. Il `sgcVer.inc` del prodotto non contiene alcun define `SGC_EDT_*` e nessuna funzionalità è regolata per livello. Una libreria, tutti i componenti, in ogni licenza. I livelli commerciali si distinguono per numero di postazioni: single, team e site, più una Community Edition gratuita.
Piattaforma, verificata nel sorgente	Win32, Win64, Linux64, OSX64, OSXARM64, iOS e Android. La crittografia passa da una unit di raccordo, `sgcSign_Crypto.pas`, che è CNG su Windows e Pascal puro ovunque altrove, HTTP è WinHTTP su Windows e il client RTL di Delphi altrove, e i package di runtime abilitano Linux64 e macOS su Intel da Delphi 10.3, Android e iOS dalla 10.4 e macOS su Apple Silicon dalla 11. `sgcSign_KeyProvider_WinCertStore.pas` è l'unica unit solo per Windows.
Dipendenze esterne	Nessuna. Su Windows la libreria chiama direttamente le API CNG e WinHTTP di Windows e sulle altre piattaforme usa la propria crittografia Pascal pura e il client HTTP della RTL di Delphi, quindi non ci sono DLL OpenSSL da distribuire con la tua applicazione.
Valori predefiniti	Un nuovo `TsgcPAdESSigner` ha già un profilo utilizzabile: il costruttore imposta il profilo PAdES di base, il livello di firma baseline B e SHA-256. Non devi toccare `Profile` per produrre una firma valida.

Preferisci XML al PDF? Il percorso XAdES di cinque minuti firma invece un documento XML con un file PFX e tratta il problema Unicode di Delphi 7 e l'ora di firma in UTC. Questa pagina è la controparte per PDF e store dei certificati.

Passo 1

Installa e trova la pagina della palette

Compila il package di runtime prima di installare quello di design-time, perché il secondo fa riferimento al primo.

1. Decomprimi

Decomprimi il download in una cartella, chiamata {$DIR} qui sotto.

2. Library path

Tools, Environment Options, Directories. Aggiungi {$DIR}\delphi\source, che vale per ogni versione di RAD Studio.

3. Aggiungi la cartella lib

Aggiungi anche la cartella specifica della versione, per esempio {$DIR}\delphi\libD13\$(Platform) su RAD Studio 13, fino a libD7 su Delphi 7. Per C++Builder vanno invece nel System Include path.

4. Compila i package

Apri Packages\sgcSignD13.groupproj per la versione del tuo IDE, oppure sgcSignC13.groupproj per C++Builder. Compila prima il package sgcSign, poi installa quello dclsgcSign.

5. Controlla la palette

Compare una pagina chiamata SGC Sign, con i firmatari, il verificatore, i client di marca temporale e OCSP e i dieci key provider. Su Windows contiene anche il firmatario e il verificatore Authenticode.

QuickStart

Firma un PDF, in circa venti righe

Scegli un certificato, crea il firmatario, puntalo al provider e chiama SignPDFFile. La prima scheda usa lo store dei certificati di Windows, la seconda un file 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;

Nota cosa non c'è. Profile non viene mai toccato, perché il costruttore imposta già un profilo PAdES di base, il livello di firma baseline B e SHA-256. Il commento sul temporaneo dell'interfaccia è della demo inclusa e l'ordine di rilascio nel blocco finally è il motivo per cui conta.

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;

L'unica differenza rispetto alla prima scheda è quale provider crei e come lo punti a una chiave. Tutto da KeyProvider := in poi è identico, e questo vale per tutti e dieci i provider, inclusi l'hardware PKCS#11 e i servizi di chiavi cloud.

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;

Stessa regola sull'interfaccia del firmatario: assegna il cast a una variabile locale con nome e azzerala prima di liberare il componente. GetValidationReportXML produce un report nel formato di validation report ETSI quando un booleano non è una prova sufficiente.

Le prime due schede provengono dalla demo inclusa Demos\Delphi\PAdES\frmMain.pas, con le sue ramificazioni ridotte a un solo percorso per scheda. Il commento sul mantenere l'interfaccia in una variabile locale con nome è della demo e vale la pena conservarlo. Una demo più ricca, Demos\Delphi\PAdES_Providers, fa lo stesso con provider hardware e cloud.

Passo 2

Controlla la firma, non limitarti a guardare il file

È comparso un file. Non è la stessa cosa di una firma che viene validata.

Il certificato è stato risolto

Leggi Certificate.Subject dopo la selezione, come fa la demo. È la differenza tra firmare con il certificato che intendevi e firmare con il primo che ha trovato una corrispondenza. IsLoaded risponde alla stessa domanda come booleano.

Il file è comparso

SignPDFFile scrive il percorso di output che gli hai dato. La demo inclusa lo ricava con ChangeFileExt in modo che il file firmato finisca accanto all'originale.

Solleva un'eccezione, non restituisce un codice

Non c'è alcun risultato da verificare, quindi metti la chiamata in un try except e leggi il messaggio dell'eccezione. È ciò che fa la demo ed è l'unico canale di errore.

La firma viene validata

Un file non è una firma valida. TsgcSignatureVerifier.VerifyPDF restituisce un TsgcVerificationStatus che confronti con vsValid e GetVerificationDetails spiega un errore. Aprire il file in un lettore PDF mostra la stessa cosa a una persona.

Problemi comuni

Cosa va storto di solito la prima volta

Sei problemi spiegano quasi ogni prima firma.

Una access violation in uscita

È quella di cui la demo avverte nel proprio commento. KeyProvider accetta un IsgcKeyProvider, quindi un cast as inline lascia in vita un riferimento a interfaccia generato dal compilatore fino al ritorno della routine, cioè dopo che hai liberato il componente provider. Assegna l'interfaccia a una variabile locale con nome e rilascia nell'ordine: firmatario, poi interfaccia a nil, poi provider.

Profile non è una stringa

È un oggetto TsgcSignProfileConfig. Imposti Profile.Profile e Profile.SignatureLevel, non Profile := 'something'. Il costruttore compila già un valore predefinito utilizzabile, quindi il primo esempio non ha bisogno di toccarlo affatto.

Non viene trovato alcun certificato

SelectCertificateBySubject cerca per soggetto e SelectCertificateByThumbprint per thumbprint. Leggi Certificate.Subject dopo la selezione, come fa la demo, così vedi quale certificato hai ottenuto davvero. EnumerateCertificates elenca ciò che è disponibile.

Il provider dello store di Windows non compila fuori da Windows

TsgcWindowsCertStoreProvider, in sgcSign_KeyProvider_WinCertStore.pas, è l'unica unit che si compila solo su Windows. Su Linux, macOS, iOS e Android scegli un altro provider di chiavi, come PFX, PEM, PKCS#11 o uno dei provider cloud, e il resto della libreria funziona allo stesso modo.

La firma risulta sconosciuta nel lettore

Una firma di base non contiene alcuna ancora di fiducia né dati di revoca. Aggiungi una marca temporale tramite TSAClient e passa a un profilo a lungo termine quando il documento deve restare verificabile dopo la scadenza del certificato.

SignPDFFile solleva un'eccezione invece di restituire un codice

È una scelta di progetto. Non c'è alcun valore restituito da verificare, quindi metti la chiamata in un try except e leggi il messaggio dell'eccezione, che è ciò che fa la demo inclusa.

Approfondisci

Oltre la prima firma

Quattro direzioni, tutte nella stessa libreria.

Altri formati di documento

XAdES e XMLDSig per XML, CAdES per CMS detached, contenitori ASiC e firmatari dedicati per pacchetti ClickOnce, NuGet e VSIX. Su Windows c'è anche un firmatario Authenticode.

Tutti i componenti di sgcSign

Dove si trova la chiave

Sono inclusi dieci key provider: PFX, PEM, lo store di Windows, hardware PKCS#11, Azure Trusted Signing, AWS KMS, Google Cloud KMS, Certum SimplySign, HashiCorp Vault e il protocollo di firma remota CSC.

Key provider

Profili per paese

Ventuno profili per paese e settore, dalla VeriFactu spagnola ai formati di fatturazione UE, ciascuno con i campi e il livello di firma che quel regime si aspetta.

Profili di firma

Firma altrove

sgcSign Server è un daemon self-hosted che custodisce le chiavi e firma su richiesta, così il certificato non lascia mai la macchina di cui ti fidi.

sgcSign Server

Risorse

Riferimento, demo e documentazione

I progetti demo sono inclusi nel download, in Demos\Delphi. La demo PAdES è quella da cui è costruita questa pagina.

	Percorso XAdES di cinque minuti La guida rapida estesa: un nuovo progetto VCL, un file PFX e una busta XML firmata.	Apri
	Key provider Tutti e dieci i posti in cui può trovarsi una chiave privata e ciò che serve a ciascuno.	Apri
	Profili di firma I ventuno profili per paese e settore e ciò che ciascuno richiede.	Apri
	Tutorial sulla firma dei PDF Un percorso più lungo su PAdES, incluse le firme visibili.	Apri
	sgcSign Server Il daemon di firma self-hosted, quando la chiave non deve viaggiare.	Apri
	Scarica la versione di prova Lo stesso installer della versione di produzione, con limite di tempo, più una Community Edition gratuita.	Apri

Letture correlate: l'introduzione a sgcSign e il server di firma del codice. Ogni prodotto ha la propria guida rapida, elencata nella pagina per iniziare.

FAQ

Domande sulla guida rapida di sgcSign

TsgcPAdESSigner, dichiarato in sgcSign_PAdES.pas, e un key provider. Per lo store dei certificati di Windows è TsgcWindowsCertStoreProvider, da sgcSign_KeyProvider_WinCertStore.pas. Per un file .pfx è TsgcPFXKeyProvider, da sgcSign_KeyProvider_PFX.pas. Entrambi si trovano nella pagina SGC Sign della palette. Assegna il provider alla proprietà KeyProvider del firmatario, poi chiama SignPDFFile(aInputFile, aOutputFile).

Perché KeyProvider è tipizzato come interfaccia IsgcKeyProvider, non come componente. Un cast as inline crea un temporaneo di interfaccia generato dal compilatore che resta in vita nello stack frame fino al ritorno della routine, cioè dopo che il componente provider è stato liberato, e rilasciarlo a quel punto tocca memoria che non esiste più. La demo assegna il cast a una variabile locale con nome e poi rilascia nell'ordine: firmatario, interfaccia a nil, provider. Copia quell'ordine.

Non ci sono edizioni. Il sgcVer.inc del prodotto non contiene alcun define SGC_EDT_* e nessun componente o formato è regolato per livello. Ogni licenza contiene ogni firmatario, ogni key provider e ogni profilo per paese. I livelli commerciali sono numeri di postazioni, single, team e site, e c'è una Community Edition gratuita accanto alla versione di prova.

Sì, dalla versione 2026.10.0. La libreria compila e funziona su Linux64, su macOS per Intel e Apple Silicon, su iOS e su Android, oltre che su Win32 e Win64. Firmare e verificare documenti, leggere e scrivere file PKCS#12, firmare file PE, cataloghi, MSI, MSP, MSIX e APPX e i token PKCS#11 funzionano tutti lì, e il server di firma gira come daemon systemd su Linux. Due provider usano il keystore che la piattaforma ha già, il portachiavi Apple e l'Android KeyStore. Due cose restano su Windows: il provider dello store dei certificati di Windows e i formati specifici di Windows sul server e sullo strumento da riga di comando, che li rifiutano ancora in una build non Windows anche se la libreria stessa li firma.

Non per una prima firma. Il costruttore imposta già un profilo PAdES di base, il livello di firma baseline B e SHA-256. Quando vuoi cambiarlo, Profile è un oggetto TsgcSignProfileConfig, quindi imposti Profile.Profile e Profile.SignatureLevel invece di assegnare una stringa. Per una firma a lungo termine passa al profilo LTV e al livello baseline LT e collega un TSAClient.

Usa TsgcSignatureVerifier. VerifyPDF accetta uno stream e restituisce un TsgcVerificationStatus, che confronti con vsValid. GetVerificationDetails spiega un errore e GetValidationReportXML produce un report nel formato di validation report ETSI quando ti serve una prova e non un booleano.

No. Su Windows sgcSign calcola gli hash e firma tramite le API CNG e BCrypt e comunica in rete tramite WinHTTP. Su Linux, macOS, iOS e Android usa la propria crittografia Pascal pura e il client HTTP della RTL di Delphi. In entrambi i casi non ci sono DLL OpenSSL da distribuire, ed è uno dei motivi per cui la distribuzione è semplice.

Coprono attività diverse di proposito. La guida rapida di cinque minuti costruisce un nuovo progetto VCL, usa un file PFX e firma un documento XML con XAdES, e affronta il problema Unicode di Delphi 7 e l'ora di firma in UTC. Questa pagina firma un PDF con PAdES usando un certificato dallo store di Windows, che è ciò che fa la demo PAdES inclusa. Leggi prima questa, poi quella quando ti serve XML.

sgcSign in cinque minuti