Démarrage rapide de sgcSign

En un coup d'œil

Un signataire et un fournisseur de clés

Le signataire connaît le format du document. Le fournisseur de clés sait où se trouve la clé privée. Ils se rejoignent sur une seule propriété.

Le signataire

TsgcPAdESSigner, déclaré dans sgcSign_PAdES.pas et enregistré sur la page de palette SGC Sign. SignPDFFile prend un chemin d'entrée et un chemin de sortie.

Le fournisseur de clés

TsgcWindowsCertStoreProvider pour le magasin de certificats Windows, ou TsgcPFXKeyProvider pour un fichier .pfx. Les deux se trouvent sur la même page de palette.

La propriété qui les relie

KeyProvider, dont le type est l'interface IsgcKeyProvider plutôt qu'une référence de composant. Cette distinction compte pour la durée de vie, et la section des pièges ci-dessous explique pourquoi.

Plateforme

Win32, Win64, Linux64, macOS sur Intel et Apple Silicon, iOS et Android. Sous Windows, le hachage et la signature passent par l'API Windows CNG, sur toutes les autres plateformes par la cryptographie en pur Pascal de la bibliothèque, sans OpenSSL à déployer. Le fournisseur du magasin de certificats Windows est le seul composant qui reste réservé à Windows.

Avant de commencer

Prérequis et éditions

sgcSign n'a pas de niveaux de fonctionnalités, ce tableau porte donc sur les compilateurs et les plateformes plutôt que sur les éditions.

Quoi	Valeur
IDE	Delphi 7 jusqu'à RAD Studio 13, et C++Builder. Pour C++Builder, le dossier lib se place dans le chemin System Include plutôt que dans le chemin de bibliothèque.
Clause uses	La démo écrit `sgcSign_Types, sgcSign_Interfaces, sgcSign_Classes, sgcSign_PAdES, sgcSign_KeyProvider_WinCertStore, sgcSign_KeyProvider_PEM, sgcSign_KeyProvider_PFX`. Retire les fournisseurs que tu n'utilises pas.
Éditions	Il n'y en a aucune. Le `sgcVer.inc` propre au produit ne contient aucun define `SGC_EDT_*`, et aucune fonctionnalité n'est conditionnée par un niveau. Une seule bibliothèque, tous les composants, dans chaque licence. Les niveaux commerciaux dépendent du nombre de postes : single, team et site, plus une Community Edition gratuite.
Plateforme, vérifiée dans les sources	Win32, Win64, Linux64, OSX64, OSXARM64, iOS et Android. La cryptographie passe par une unité d'interface unique, `sgcSign_Crypto.pas`, qui utilise CNG sous Windows et du pur Pascal partout ailleurs, HTTP est WinHTTP sous Windows et le client RTL de Delphi ailleurs, et les packages d'exécution activent Linux64 et macOS sur Intel à partir de Delphi 10.3, Android et iOS à partir de 10.4, et macOS sur Apple Silicon à partir de 11. `sgcSign_KeyProvider_WinCertStore.pas` est la seule unité réservée à Windows.
Dépendances externes	Aucune. Sous Windows, la bibliothèque appelle directement les API Windows CNG et WinHTTP, et sur les autres plateformes elle utilise sa propre cryptographie en pur Pascal et le client HTTP de la RTL Delphi, il n'y a donc aucune DLL OpenSSL à déployer avec ton application.
Valeurs par défaut	Un `TsgcPAdESSigner` neuf a déjà un profil utilisable : le constructeur définit le profil PAdES de base, le niveau de signature baseline B et SHA-256. Tu n'as pas besoin de toucher à `Profile` pour produire une signature valide.

Tu préfères le XML au PDF ? Le pas à pas XAdES en cinq minutes signe un document XML avec un fichier PFX, et traite le piège Unicode de Delphi 7 et l'heure de signature en UTC. Cette page est la contrepartie PDF et magasin de certificats.

Étape 1

Installer et trouver la page de palette

Compile le package d'exécution avant d'installer celui de conception, car le second référence le premier.

1. Décompresser

Décompresse le téléchargement dans un dossier, appelé {$DIR} ci-dessous.

2. Chemin de bibliothèque

Outils, Options d'environnement, Répertoires. Ajoute {$DIR}\delphi\source, qui s'applique à toutes les versions de RAD Studio.

3. Ajouter le dossier lib

Ajoute aussi le dossier propre à ta version, par exemple {$DIR}\delphi\libD13\$(Platform) sur RAD Studio 13, jusqu'à libD7 sur Delphi 7. Pour C++Builder, ils vont plutôt dans le chemin System Include.

4. Compiler les packages

Ouvre Packages\sgcSignD13.groupproj pour ta version d'IDE, ou sgcSignC13.groupproj pour C++Builder. Compile d'abord le package sgcSign, puis installe celui nommé dclsgcSign.

5. Vérifier la palette

Une page nommée SGC Sign apparaît, contenant les signataires, le vérificateur, les clients d'horodatage et OCSP, et les dix fournisseurs de clés. Sous Windows, elle contient aussi le signataire et le vérificateur Authenticode.

QuickStart

Signer un PDF, en une vingtaine de lignes

Choisis un certificat, crée le signataire, pointe-le vers le fournisseur et appelle SignPDFFile. Le premier onglet utilise le magasin de certificats Windows, le deuxième un fichier 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;

Remarque ce qui n'est pas là. Profile n'est jamais touché, car le constructeur définit déjà un profil PAdES de base, le niveau de signature baseline B et SHA-256. Le commentaire sur la temporaire d'interface est celui de la démo livrée, et l'ordre de libération dans le bloc finally est la raison pour laquelle il compte.

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;

La seule différence avec le premier onglet est le fournisseur que tu crées et la façon de le pointer vers une clé. Tout ce qui suit KeyProvider := est identique, et cela vaut pour les dix fournisseurs, y compris le matériel PKCS#11 et les services de clés 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;

La même règle d'interface que pour le signataire : affecte le cast à une variable locale nommée et vide-la avant de libérer le composant. GetValidationReportXML produit un rapport au format de rapport de validation ETSI quand un booléen ne constitue pas une preuve suffisante.

Les deux premiers onglets proviennent de la démo livrée Demos\Delphi\PAdES\frmMain.pas, dont les branchements ont été réduits à un chemin par onglet. Le commentaire sur le maintien de l'interface dans une variable locale nommée est celui de la démo, et il vaut la peine d'être conservé. Une démo sœur plus riche, Demos\Delphi\PAdES_Providers, fait la même chose avec des fournisseurs matériels et cloud.

Étape 2

Vérifier la signature, ne pas se contenter de regarder le fichier

Un fichier est apparu. Ce n'est pas la même chose qu'une signature qui se valide.

Le certificat a été résolu

Lis Certificate.Subject après la sélection, comme le fait la démo. C'est la différence entre signer avec le certificat voulu et signer avec le premier qui a correspondu. IsLoaded répond à la même question sous forme de booléen.

Le fichier est apparu

SignPDFFile écrit le chemin de sortie que tu lui as donné. La démo livrée le dérive avec ChangeFileExt pour que le fichier signé se place à côté de l'original.

Il lève une exception, il ne renvoie pas de code

Il n'y a aucun résultat à tester, place donc l'appel dans un try except et lis le message de l'exception. C'est ce que fait la démo, et c'est le seul canal d'échec.

La signature se valide

Un fichier n'est pas une signature valide. TsgcSignatureVerifier.VerifyPDF renvoie un TsgcVerificationStatus que tu compares à vsValid, et GetVerificationDetails explique un échec. Ouvrir le fichier dans un lecteur PDF montre la même chose à une personne.

Problèmes courants

Ce qui se passe généralement mal la première fois

Six problèmes expliquent presque toutes les premières signatures.

Une violation d'accès à la sortie

C'est celle dont la démo met en garde dans son propre commentaire. KeyProvider prend un IsgcKeyProvider, donc un cast as en ligne laisse vivante une référence d'interface générée par le compilateur jusqu'au retour de la routine, c'est-à-dire après que tu as libéré le composant fournisseur. Affecte l'interface à une variable locale nommée, et libère dans l'ordre : signataire, puis interface à nil, puis fournisseur.

Profile n'est pas une chaîne

C'est un objet TsgcSignProfileConfig. Tu définis Profile.Profile et Profile.SignatureLevel, pas Profile := 'something'. Le constructeur renseigne déjà une valeur par défaut utilisable, le premier exemple n'a donc pas besoin d'y toucher.

Aucun certificat n'est trouvé

SelectCertificateBySubject recherche sur le sujet, et SelectCertificateByThumbprint sur l'empreinte. Lis Certificate.Subject après la sélection, comme le fait la démo, pour voir quel certificat tu as réellement obtenu. EnumerateCertificates liste ce qui est disponible.

Ça ne compile pas hors Windows

C'est impossible. Le signataire et chaque fournisseur placent Windows dans la clause uses de l'interface sans condition, c'est donc une erreur de compilation plutôt qu'une unité vide. sgcSign est une bibliothèque Windows.

La signature apparaît comme inconnue dans le lecteur

Une signature de base ne contient ni ancre de confiance ni données de révocation. Ajoute un horodatage via TSAClient, et passe à un profil à long terme quand le document doit rester vérifiable après l'expiration du certificat.

SignPDFFile lève une exception au lieu de renvoyer un code

C'est voulu. Il n'y a aucune valeur de retour à tester, place donc l'appel dans un try except et lis le message de l'exception, ce que fait la démo livrée.

Aller plus loin

Au-delà de la première signature

Quatre directions, toutes dans la même bibliothèque.

Autres formats de documents

XAdES et XMLDSig pour le XML, CAdES pour le CMS détaché, les conteneurs ASiC, et des signataires dédiés pour les packages ClickOnce, NuGet et VSIX. Sous Windows, il existe aussi un signataire Authenticode.

Tous les composants sgcSign

Où se trouve la clé

Dix fournisseurs de clés sont livrés : PFX, PEM, le magasin Windows, le matériel PKCS#11, Azure Trusted Signing, AWS KMS, Google Cloud KMS, Certum SimplySign, HashiCorp Vault et le protocole de signature distante CSC.

Fournisseurs de clés

Profils par pays

Vingt et un profils par pays et par secteur, du VeriFactu espagnol aux formats de facturation de l'UE, chacun avec les champs et le niveau de signature qu'exige ce régime.

Profils de signature

Signer ailleurs

sgcSign Server est un démon auto-hébergé qui détient les clés et signe à la demande, de sorte que le certificat ne quitte jamais la machine à laquelle tu fais confiance.

sgcSign Server

Ressources

Référence, démos et documentation

Les projets de démo sont livrés dans le téléchargement, sous Demos\Delphi. La démo PAdES est celle sur laquelle cette page est construite.

	Pas à pas XAdES en cinq minutes Le démarrage rapide détaillé : un nouveau projet VCL, un fichier PFX et une enveloppe XML signée.	Ouvrir
	Fournisseurs de clés Les dix endroits où une clé privée peut se trouver, et ce dont chacun a besoin.	Ouvrir
	Profils de signature Les vingt et un profils par pays et par secteur, et ce que chacun exige.	Ouvrir
	Tutoriel de signature PDF Un pas à pas plus long de PAdES, y compris les signatures visibles.	Ouvrir
	sgcSign Server Le démon de signature auto-hébergé, quand la clé ne doit pas voyager.	Ouvrir
	Télécharger l'essai Le même installeur que la version de production, limité dans le temps, plus une Community Edition gratuite.	Ouvrir

Lectures associées : l'introduction à sgcSign et le serveur de signature de code. Chaque produit a son propre démarrage rapide, listé sur la page de prise en main.

FAQ

Questions sur le démarrage rapide de sgcSign

TsgcPAdESSigner, déclaré dans sgcSign_PAdES.pas, et un fournisseur de clés. Pour le magasin de certificats Windows, c'est TsgcWindowsCertStoreProvider, de sgcSign_KeyProvider_WinCertStore.pas. Pour un fichier .pfx, c'est TsgcPFXKeyProvider, de sgcSign_KeyProvider_PFX.pas. Les deux se trouvent sur la page de palette SGC Sign. Affecte le fournisseur à la propriété KeyProvider du signataire, puis appelle SignPDFFile(aInputFile, aOutputFile).

Parce que KeyProvider est typé comme l'interface IsgcKeyProvider, et non comme un composant. Un cast as en ligne crée une temporaire d'interface générée par le compilateur qui reste vivante dans le cadre de pile jusqu'au retour de la routine, c'est-à-dire après la libération du composant fournisseur, et la libérer alors touche une mémoire qui n'existe plus. La démo affecte le cast à une variable locale nommée puis libère dans l'ordre : signataire, interface à nil, fournisseur. Copie cet ordre.

Il n'y a pas d'éditions. Le sgcVer.inc du produit ne contient aucun define SGC_EDT_*, et aucun composant ni format n'est conditionné par un niveau. Chaque licence contient chaque signataire, chaque fournisseur de clés et chaque profil par pays. Les niveaux commerciaux dépendent du nombre de postes, single, team et site, et il existe une Community Edition gratuite en plus de l'essai.

Oui, depuis la version 2026.10.0. La bibliothèque se compile et s'exécute sous Linux64, sous macOS pour Intel et Apple Silicon, sous iOS et sous Android, ainsi que Win32 et Win64. La signature et la vérification de documents, la lecture et l'écriture de fichiers PKCS#12, la signature de fichiers PE, de catalogues, MSI, MSP, MSIX et APPX, et les jetons PKCS#11 y fonctionnent tous, et le serveur de signature s'exécute comme démon systemd sous Linux. Deux fournisseurs utilisent le magasin de clés que la plateforme possède déjà, le trousseau Apple et l'Android KeyStore. Deux éléments restent sous Windows : le fournisseur du magasin de certificats Windows, et les formats propres à Windows sur le serveur et l'outil en ligne de commande, qui les refusent encore sur une version qui n'est pas Windows bien que la bibliothèque elle-même les signe.

Pas pour une première signature. Le constructeur définit déjà un profil PAdES de base, le niveau de signature baseline B et SHA-256. Quand tu veux le changer, Profile est un objet TsgcSignProfileConfig, tu définis donc Profile.Profile et Profile.SignatureLevel au lieu d'affecter une chaîne. Pour une signature à long terme, passe au profil LTV et au niveau baseline LT, et attache un TSAClient.

Utilise TsgcSignatureVerifier. VerifyPDF prend un flux et renvoie un TsgcVerificationStatus, que tu compares à vsValid. GetVerificationDetails explique un échec, et GetValidationReportXML produit un rapport au format de rapport de validation ETSI quand tu as besoin d'une preuve plutôt que d'un booléen.

Non. Sous Windows, sgcSign hache et signe via les API CNG et BCrypt et communique avec le réseau via WinHTTP. Sous Linux, macOS, iOS et Android, il utilise sa propre cryptographie en pur Pascal et le client HTTP de la RTL Delphi. Dans les deux cas, il n'y a aucune DLL OpenSSL à livrer, ce qui est l'une des raisons pour lesquelles le déploiement est simple.

Ils couvrent volontairement des tâches différentes. Le démarrage rapide en cinq minutes construit un nouveau projet VCL, utilise un fichier PFX et signe un document XML avec XAdES, et il aborde le piège Unicode de Delphi 7 et l'heure de signature en UTC. Cette page signe un PDF avec PAdES en utilisant un certificat du magasin Windows, ce que fait la démo PAdES livrée. Lis celle-ci d'abord, puis l'autre quand tu as besoin du XML.

sgcSign en cinq minutes